Getting Started

This guide walks you through the steps required to set up your environment, configure your API access, and run use case scripts to explore the Locktera API's functionality.

---

Getting Started

1. Clone this repository to your local machine:

   git clone https://github.com/Locktera/api-docs.git

2. Log in to Locktera Share and go to the API Keys page

3. Create a new API key.

4. Edit the env file in the repository root.

5. Copy/Paste your ORG_ID and API_KEY values into the env file and save it.

   API_URL=https://test.locktera.com/api/v1/
   ORG_ID=your_org_id_here
   API_KEY=your_api_key_here

6. Explore the Use Case directory.

7. For further information, check the API reference

---

Running TypeScript Use Cases

Prerequisites

• Node.js v20 or higher

Installation

1. Navigate to this directory
2. Install dependencies:

   npm install

Running a Use Case

1. Navigate to the directory of the use case you wish to run:

   cd encode
2. Run the use case using npm run $NAME:

   npm run encode

---

Use Cases

See the documentation for the following use cases:

Writing DRM Rules

Modify DRM rules on an existing container.

Encode a folder

Encode a new Locktera container.

---

Code Overview

Available Scripts

Script	Description
drm/main.ts	Modify DRM rules on an existing container.
encode/main.ts	Encode a new Locktera container.
fetch.ts	Fetch organizational data securely.
DynamicDrm.ts	Defines modifiable DRM rules for containers.
Manifest.ts	Defines structure for container metadata.

---

TypeScript Files

DynamicDrm.ts

The DynamicDrm.ts file defines modifiable DRM rules for containers.

import { type Drm } from './Manifest.ts';

/** DRM rules modifiable after container creation */
export type DynamicDrm = Drm & {
	/** See `ContainerInfo.recipients` */
	recipients?: string[];

	/** See `ContainerInfo.downloadable` */
	downloadable: boolean;
};

---

Fetch.ts

The fetch.ts file handles API requests with authorization headers.

import * as dotenv from 'dotenv';
import * as path from 'node:path';

// Get the absolute path of this file
const DIRNAME = path.dirname(new URL(import.meta.url).pathname);

// Load IDs and keys from the env file in the repository root
dotenv.config({ path: path.join(DIRNAME, '../../env') });

export const API_URL = process.env.API_URL;
export const ORG_ID = process.env.ORG_ID;
export const API_KEY = process.env.API_KEY;

if (!API_URL) throw new Error('API_URL is required');
if (!ORG_ID) throw new Error('ORG_ID is required');
if (!API_KEY) throw new Error('API_KEY is required');

async function api_fetch (url: string, init?: RequestInit) {
    // Combine the base API URL and remove duplicate slashes
    url = path.join(API_URL!, url);

    // Add the Authorization header containing the API key
    init = {
        ...init,
        headers: {
            ...init?.headers,
            'authorization': `Bearer ${API_KEY}`,
        },
    };

    const response = await fetch(url, init);

    if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message);
    }

    return await response.json();
}

export async function verify_identity () {
    // Fetch our org information
    const org_data = await api_fetch(`/orgs/${ORG_ID}`);
    console.log('Logged in as:', org_data.email);
}

export {
    api_fetch as default,
    api_fetch as fetch
};

---

Manifest.ts

The Manifest.ts file defines the structure and types for handling Locktera container metadata, such as DRM rules, recipients, and download permissions.

/** Locktera container manifest */
export type Manifest = {
    /** Information about the container itself */
    container: ContainerInfo;

    /** Information about each content file, indexed by name */
    files?: Record<string, FileInfo>;
};

/** Information about the container itself */
export type ContainerInfo = {
    /**
     * A list of email addreses, with an optional wilcdard on either side of the `@`, e.g.:
     * - `example@gmail.com`: A single email address
     * - `*@locktera.com`: Any email from a given domain
     * - `*@*,`: Any logged-in viewer, regardless of email address
     */
    recipients?: string[];

    /** Whether or not the content is downloadable. Only applies to viewers; the sender can always download all content */
    downloadable: boolean;

    /** Password to use for encryption, if desired. If provided, viewers must enter this password to decrypt the contents. */
    password?: string;

    /** Desired DRM rules */
    drm?: Drm;
};

/** Container-wide access rules */
export type Drm = {
    /**
     * Whether the DRM should be modifiable after the container is encoded; default false.
     * If true, the DRM will be stored in the Locktera database and be modifiable by API. If false, the DRM will be encrypted directly in the container and cannot be modified.
     */
    dynamic?: boolean;

    /** Geolocation rules */
    geo?: DrmRules<GeoRule>;

    /**
     * IPv4 address rules. The following formats are supported:
     * - `192.168.1.10`: Single IP address
     * - `192.168.1.0/24`: Subnet mask
     * - `192.*.1.*`: Wildcard
     * - `192.168.1.0-192.168.1.255`: Range
     * - `192.168.1.10/255.0.255.0`: IP mask
     */
    ip?: DrmRules<string>;

    /** The number of times each viewer can open the container */
    opens?: number;

    /** The time range for which the content is accessible */
    time?: TimeRule;
};

/**
 * List of allow and block rules of a particular type. For each type of DRM rule:
 * - If any allow rules are specified, only allow a viewer who matches an allow rule
 * - If there are only block rules, only allow a viewer who does not match any block rules
 */
export type DrmRules<T> = {
    /** Allow viewers matching these rules to access the content */
    allow?: T[];

    /** Block viewers matching these rules from accessing the content */
    block?: T[];
};

/** Geolocation rule */
export type GeoRule = {
    /** Continent name */
    continent?: string;

    /** Country name */
    country?: string;

    /** Subdivision (e.g. prefecture, province, state, county) */
    subdivision?: string;

    /** City name */
    city?: string;
};

/** Time-range rule */
export type TimeRule = {
    /** The time before which the content is inaccessible */
    start?: Date;

    /** The time after which the content is inaccessible */
    end?: Date;
};

/** Information about one content file */
export type FileInfo = {
    /** Content type of the file */
    type?: string;

    /** Number of pages in a document */
    pages?: number;

    /** Duration of a media file in seconds */
    duration?: number;

    /** Whether the file should be hidden from the viewer menu; default false */
    hidden?: boolean;

    /** Name of a file to view instead of this file when it is chosen from the menu */
    view_instead?: string;

    /** Name of a file to download instead of this file when the download button is pressed */
    download_instead?: string;
};

---

Accessing TypeScript Files on GitHub

For full TypeScript implementations, visit the GitHub repository.

• drm/main.ts: Modify DRM rules on an existing container.
• encode/main.ts: Encode a new Locktera container.
• DynamicDrm.ts: Dynamic DRM configurations.
• fetch.ts: API request handling.
• Manifest.ts: Defines structure for container metadata.
• main.ts: Entry point for running use cases.

Use these files in conjunction with the use cases to understand the Locktera API.